DMDisableDisplay

DMDisableDisplay
Header:	Displays.h		Carbon status:	Supported

Makes a video device inactive by removing its display area from the desktop. You should generally never need to use this function.

OSErr DMDisableDisplay (
    GDHandle disableDevice, 
    Handle displayState
);

Parameter descriptions

disableDevice: A handle to the GDevice structure for the video device whose display you wish to disable.
displayState: If your application called DMBeginConfigureDisplays, you must pass the displayState handle obtained. Otherwise pass NULL in this parameter.

function result: A result code.

DISCUSSION

You are not allowed to disable the last remaining display. Doing so will simply re-enable it. If you want to remove the last remaining display, thereby enabling the GDevice structure not associated with any video device, call the function DMRemoveDisplay.

If you specify the device for the main screen in the disableDevice parameter, then DMDisableDisplay picks another device and makes it the new main screen.

If DMDisableDisplay results in setting a new main screen, the handle you pass in the disableDevice parameter does not point to the same GDevice structure after DMDisableDisplay completes; instead, it points to the GDevice structure for the new main screen. If you need to recover the GDevice structure for the device you disabled, determine its display ID by using the function DMGetDisplayIDByGDevice before calling DMDisableDisplay. Then use the function DMGetGDeviceByDisplayID to obtain its structure.

SPECIAL CONSIDERATIONS

Because this function may move or purge memory blocks or access handles, you cannot call it at interrupt time.

Applications generally never need to use this function. In case you find a compelling need to change the user’s display configuration, this function is described here for completeness. Note that if your application uses Display Manager functions to change the display configuration of the user’s video devices, your application should make these changes only with the consent of the user. If your application must have a specific pixel depth, for example, it should display a dialog box that offers the user a choice between changing to that depth or canceling display of the image.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.